home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 26 / Cream of the Crop 26.iso / os2 / os2mb106.zip / RXFile.doc < prev    next >
Text File  |  1997-05-20  |  29KB  |  821 lines

  1. RXFile: A Rexx I/O class implementation  1.13 - Max Marsiglietti 1996.
  2.  
  3. This is the official RXFile documentation. You'll find here all the 
  4. information you need for using the RXFile library for NetRexx.
  5.  
  6. To get best results in visualization of this document, use a monospaced font.
  7. English is not my language. Please adjust your instruments accordingly. :)
  8.  
  9. INDEX:
  10.  1.... Introduction
  11.   1.1.   - What is RXFile.
  12.  
  13.  
  14.  2.... Use of the RXFile class 
  15.   2.1    - in Java.
  16.   2.2    - in NetRexx.
  17.   2.3    - A detailed explanation of all the methods.
  18.    2.3.1   - Before we begin.
  19.    2.3.2   ** RXFile constructors in NetRexx **
  20.    2.3.3   ** The STREAM method **
  21.    2.3.4   ** The CHARS method **
  22.    2.3.5   ** The LINES method **
  23.    2.3.6   ** The CHARIN method **
  24.    2.3.7   ** The LINEIN method **
  25.    2.3.8   ** The CHAROUT method **
  26.    2.3.9   ** The LINEOUT method **
  27.  
  28.    2.3.10  ** The DELETE method **
  29.    2.3.11  ** The RENAME method **
  30.    2.3.12  ** The MKDIR method **
  31.    2.3.13  ** The MKDIRS method **
  32.    2.3.14  ** The PROPERTIES method **
  33.    2.3.15  ** The FILETREE method **
  34.    2.3.16  ** The SETPARMS method **
  35.    2.3.17  ** The GETPARMS method **
  36.    2.3.18  ** The ADDCURSOR method **
  37.    2.3.19  ** The GETCURSOR method **
  38.    2.3.20  ** The DELCURSOR method **
  39.    2.3.21  ** The DELALLCURSORS method **
  40.    2.3.22  ** The ATTACHTOINPUTSTREAM method **
  41.    2.3.23  ** The ATTACHTOOUTPUTSTREAM method **
  42.    2.3.24  ** The COPY method **
  43.  
  44.  
  45.  3.... Other stuff
  46.   3.1    - This package contents.
  47.   3.2    - License.
  48.   3.3    - Contacting the author.
  49.   3.4    - Release History.
  50.  
  51.  
  52.  
  53. 1. I N T R O D U C T I O N
  54. --------------------------
  55.  
  56. Notice: NetRexx, OS/2 are copyright of IBM Corp.
  57.         JAVA is a copyright of SUN Microsystems, Inc.
  58.  
  59. Other trademarks in this document are owned by the respective companies.
  60. Whatever. :)
  61.  
  62. Warning: in this document I will assume that the reader knows
  63. what NetRexx is and how to build applications in NetRexx.
  64. JAVA I/O specific knowledge it's not required.
  65.  
  66. Many people think that JAVA is only useful for writing web applets;
  67. it is my opinion that this statement is reductive.
  68. JAVA makes a great language for a variety of purposes, expecially
  69. those requiring cross-platform development.
  70.  
  71. One of the less-explored areas of what I call 'the jungle of JAVA
  72. APIs' is the one that deals with streams and files in general.
  73. While there is in the JAVA developer's toolkit a plethora of examples
  74. to show how easy and cool is doing graphics with this language,
  75. there is not a single example specific to file usage.
  76. Not that JAVA is lacking stuff, it's only that this stuff is
  77. buried under the documentation. 
  78.  
  79. The JAVA approach approach to files and streams is somewhat confusing;
  80. there are many classes, a bunch of interfaces, and some of these
  81. apparently aren't so useful for the everyday work of Joe Programmer.
  82. That's what this package is for: helping you to manage files 
  83. and streams in Java through the use of the NetRexx compiler.
  84.  
  85.  
  86. 1.1 What is RXFile.
  87. -------------------
  88.  
  89. RXFile is a JAVA CLASS that contains a number of functions that
  90. deal with files and stdin/stdout streams.
  91.  
  92. RXFile was born to fill a gap in the NetRexx implementation;
  93. therefore, most of the methods in this class follow the syntax
  94. of the corresponding REXX statements.
  95. NetRexx is a compiler that comes as a JAVA executable and therefore
  96. can be used on every platform that has a JAVA implementation; 
  97. it produces JAVA binary code and, optionally, a JAVA source.
  98. The source language accepted by this compiler is a REXX-like 
  99. language.
  100.  
  101. NetRexx is required in order to use this class, at least the
  102. classes; download them from the URL below, and add them to
  103. your Java developing environment.
  104. All the examples are written in NetRexx, but the API syntax
  105. in this document follows the Java syntax.
  106.  
  107. To find out more, point your browser to: 
  108. http://www2.hursley.ibm.com/netrexx/
  109.  
  110.  
  111.  
  112. 2. U S E  O F  T H E  R X F I L E  C L A S S 
  113. --------------------------------------------
  114.  
  115.  
  116. 2.1 In JAVA:
  117. ------------
  118.  
  119. Just make sure that your Java environment variables
  120. knows where RXFile.class is stored, then you can just
  121. add this line to your source:
  122.  
  123. import RXFile;
  124.  
  125. along with the required NetRexx imports.
  126.  
  127.  
  128. 2.2 In NetRexx:
  129. ---------------
  130.  
  131.  import RXFile
  132.  
  133. Is required in your NetRexx source file.
  134.  
  135.  
  136.  
  137. 2.3 A detailed explanation of all the methods.
  138. ----------------------------------------------
  139.  
  140.  Why did I state 'methods', and not also 'properties' or 'exceptions' ?
  141. Simply put, the RXFile class has no public properties (variables), 
  142. and doesn't throw exceptions. Instead, it has methods to find out
  143. if there have been errors, and to query the value of some properties.
  144.  
  145.  
  146. 2.3.1 Before we begin
  147. ---------------------
  148.  
  149. The following instructions are designed to be 100% compatible with the original
  150. IBM SAA REXX implementation, so if you find any discrepancy, write to the author.
  151. (Go to the end of the document for more information)
  152.  
  153. Note: As you may know, the newline sequence is not standard among the operating
  154. systems. I.e., in Unix it's \n, in DOS-Win-OS/2 is \r\n, in Macs is \r etc.
  155. RXFile automatically sets the correct newline (currently \n, \r and \r\n are
  156. supported, since I know of these), but you can override this choice with
  157. the 'setparms' function.
  158.  
  159.  
  160. 2.3.2 ** RXFile constructors in NetRexx **
  161. ------------------------------------------
  162.  
  163. Note that the semicolon is optional:
  164.  
  165. Myfile = RXFile();
  166.  
  167. or
  168.  
  169. Myfile = RXFile("filename");
  170.  
  171. or
  172.  
  173. Myfile = RXFile(InputStream isInputStream , OutputStream osOutputStream )
  174.  
  175. This constructor assigns isInputStream, osOutputStream to the in/out
  176. streams that are normally given to console.
  177.  
  178. or
  179.  
  180. Myfile = RXFile("filename", "c", "command");
  181.  
  182. The above constructor works as in the STREAM method.
  183.  
  184. The default return strings for the following functions are: 
  185.  SYNTAX ERROR:
  186.  READY:       (no errors)
  187.  NOTREADY:32  (file in use)
  188.  NOTREADY:110 (file not found)
  189.  NOTREADY:EOF (end of file reached)
  190.  WEIRD ERROR: (this is a catch for bugs)
  191.  NOFILEOPEN:  (if the user requested an operation to be done only on open files)
  192.  ILLEGAL:WRONG ACCESS MODE (i.e. if you try to read a write-only file)
  193.  ILLEGAL:ALREADY EXISTS    (if the command implied creation of something)
  194.  ILLEGAL:CANT ACCESS TARGET
  195.  ILLEGAL:ALREADY INIT       (used for the setparms command)
  196.  
  197. Unless stated otherwise.
  198.  
  199.  
  200. 2.3.3 ** The STREAM method **
  201. -----------------------------
  202.  
  203. Used to open/close a file, query information about that file 
  204. and/or status, and seek the file cursor to a given location.
  205.  
  206. Rexx status = RXFile.stream(Rexx filename, "c", Rexx command);
  207. Rexx status = RXFile.stream("c", Rexx command);
  208. Rexx status = RXFile.stream("d");
  209. Rexx status = RXFile.stream("s");
  210.  
  211. More in details:
  212.  
  213.  
  214. Rexx status = RXFile.stream(Rexx filename, "c", Rexx command);
  215.  
  216. The commands available are:
  217. "open"           opens a file for read and write operations.
  218. "open read"      opens a file for read operations.
  219. "open write"     opens a file for write operations.
  220. "query exists"   returns the absolute path name, or the null string if
  221.                  that file doesn't exists.
  222. "query size"     returns the size, in bytes, of the file.
  223. "query datetime" returns a value useful for file comparisons (it
  224.                   doesn't return a REAL date & time, due to the
  225.                   lack of such an API in JAVA).
  226. "close"          closes the stream.
  227.  
  228. Warning: if you issue one of the next three commands when you
  229. are in 'separate r/w cursors' mode, you actually move both cursors.
  230.  
  231. Warning 2: In REXX, the first byte of the stream is at position '1', not
  232. '0' like Java. Therefore, if you do an absolute seek ('=N'), you should
  233. remember that to seek the first byte in the stream you have to
  234. issue "seek =1". All the other seek instructions are relative, so you
  235. can specify an offset = 0.
  236.  
  237. "seek =N"        The stream cursor is positioned to absolute position N 
  238.                  (in bytes; an ASCII newline is \r\n == two bytes).
  239. "seek -N"        The stream cursor is positioned N bytes back from the
  240.                  current position.
  241. "seek +N"        The stream cursor is positioned N bytes forward from the
  242.                  current position.
  243. "seek <N"        The stream cursor is positioned N bytes back from the
  244.                  end of the file.
  245.  
  246. Functions available only if you choose separate r/w cursors: 
  247. (see the SETPARMS function)
  248.  
  249. "rseek =N"        The stream read cursor is positioned to absolute position N 
  250.                  (in bytes; an ASCII newline is \r\n == two bytes).
  251. "rseek -N"        The stream read cursor is positioned N bytes back from the
  252.                  current position.
  253. "rseek +N"        The stream read cursor is positioned N bytes forward from the
  254.                  current position.
  255. "rseek <N"        The stream read cursor is positioned N bytes back from the
  256.                  end of the file.
  257. "wseek =N"        The stream write cursor is positioned to absolute position N 
  258.                  (in bytes; an ASCII newline is \r\n == two bytes).
  259. "wseek -N"        The stream write cursor is positioned N bytes back from the
  260.                  current position.
  261. "wseek +N"        The stream write cursor is positioned N bytes forward from the
  262.                  current position.
  263. "wseek <N"        The stream write cursor is positioned N bytes back from the
  264.                  end of the file.
  265.  
  266. Rexx status = RXFile.stream("c", Rexx command);
  267.  
  268. This command can be issued only when a file 
  269. has already been opened by executing a .stream call.
  270.  
  271. The commands available are:
  272. "close"          closes the stream.
  273. "query exists"   returns the absolute path name, or the null string.
  274. "query size"     returns the size, in bytes, of the file.
  275. "query datetime" returns a value useful for file comparisons (it
  276.                   doesn't return a REAL date & time, due to the
  277.                   lack of such an API in JAVA).
  278.  
  279. Warning: if you issue one of the next three commands when you
  280. are in 'separate r/w cursors' mode, you actually move both cursors.
  281.  
  282. Warning 2: In REXX, the first byte of the stream is at position '1', not
  283. '0' like Java. Therefore, if you do an absolute seek ('=N'), you should
  284. remember that to seek the first byte in the stream you have to
  285. issue "seek =1". All the other seek instructions are relative, so you
  286. can specify an offset = 0.
  287.  
  288. "seek =N"        The stream cursor is positioned to absolute position N 
  289.                  (in bytes; an ASCII newline is \r\n == two bytes).
  290. "seek -N"        The stream cursor is positioned N bytes back from the
  291.                  current position.
  292. "seek +N"        The stream cursor is positioned N bytes forward from the
  293.                  current position.
  294. "seek <N"        The stream cursor is positioned N bytes back from the
  295.                  end of the file.
  296.  
  297. Functions available only if you choose separate r/w cursors: 
  298. (see the SETPARMS function)
  299.  
  300. "rseek =N"        The stream read cursor is positioned to absolute position N 
  301.                  (in bytes; an ASCII newline is \r\n == two bytes).
  302. "rseek -N"        The stream read cursor is positioned N bytes back from the
  303.                  current position.
  304. "rseek +N"        The stream read cursor is positioned N bytes forward from the
  305.                  current position.
  306. "rseek <N"        The stream read cursor is positioned N bytes back from the
  307.                  end of the file.
  308. "wseek =N"        The stream write cursor is positioned to absolute position N 
  309.                  (in bytes; an ASCII newline is \r\n == two bytes).
  310. "wseek -N"        The stream write cursor is positioned N bytes back from the
  311.                  current position.
  312. "wseek +N"        The stream write cursor is positioned N bytes forward from the
  313.                  current position.
  314. "wseek <N"        The stream write cursor is positioned N bytes back from the
  315.                  end of the file.
  316.  
  317.  
  318. Rexx status = RXFile.stream("d");
  319. Rexx status = RXFile.stream("s");
  320.  
  321. Both these commands return the status of the stream.
  322. (they can be issued only when a file has already been opened by
  323. executing a .stream call)
  324.  
  325. The difference between them is that the latter form is more terse,
  326. the former is more verbose.
  327.  
  328.  
  329. 2.3.4 ** The CHARS method **
  330. ----------------------------
  331.  
  332. Rexx RXFile.chars();
  333. Rexx RXFile.chars(Rexx rFileName);
  334.  
  335. This method lets you know if there are, and how many are they, 
  336. characters to be read in a stream or standard input.
  337.  
  338. More in details:
  339.  
  340. Rexx RXFile.chars();
  341.  
  342. This method returns how many bytes are present in the
  343. currently opened stream. If no stream is currently open,
  344. it returns with the number of the available bytes from
  345. stdin (Warning: this doesn't work right now for stdin; 
  346. it always returns '0').
  347.  
  348. Rexx RXFile.chars(Rexx rFileName);
  349.  
  350. *This method works with files only, no standard input.*
  351.  
  352. This method returns how many bytes are present in the
  353. file rFileName.
  354. rFileName is opened with both read and write access 
  355. permissions, and a precedently open file, if exists, is closed.
  356.  
  357. Of course, if the file name is the same of the one which is
  358. (if any) currently in use, the file won't be touched, meaning
  359. that the r/w cursors will be left untouched.
  360.  
  361. The only exception is the following: if you opened rFileName 
  362. precedently with only read OR write permissions, the file will be
  363. closed and then reopened with read+write permissions.
  364. This is because lines(filename) opens the file with both read
  365. and write access capabilities.
  366.  
  367. After this operation, the currently opened file is rFileName.
  368.  
  369.  
  370. 2.3.5 ** The LINES method **
  371. ----------------------------
  372.  
  373. Rexx RXFile.lines();
  374. Rexx RXFile.lines(Rexx rFileName);
  375.  
  376. This method lets you know if there are still lines to be read
  377. in a stream or standard input.
  378.  
  379. More in details:
  380.  
  381. Rexx RXFile.lines();
  382.  
  383. This method returns "1" if there are more lines to be read 
  384. (or overwritten) in the file currently in use, else it returns "0" .
  385. If no stream is opened, it checks for the presence of lines
  386. to be read in stdin .
  387.  
  388. Rexx RXFile.lines(Rexx rFileName);
  389.  
  390. *This method works with files only, no standard input.*
  391.  
  392. This method returns "1" if there are more lines to be read 
  393. (or overwritten) in the file rFileName, else it returns "0" .
  394. rFileName is opened with both read and write access permissions, 
  395. and a precedently open file, if exists, is closed.
  396.  
  397. Of course, if the file name is the same of the one which is
  398. (if any) currently in use, the file won't be touched, meaning
  399. that the r/w cursors will be left untouched.
  400.  
  401. The only exception is the following: if you opened rFileName 
  402. precedently with only read OR write permissions, the file will be
  403. closed and then reopened with read+write permissions.
  404. This is because linein(filename) opens the file with both read
  405. and write access capabilities.
  406.  
  407. After this operation, the currently opened file is rFileName.
  408.  
  409.  
  410. 2.3.6 ** The CHARIN method **
  411. -----------------------------
  412.  
  413. Rexx RXFile.charin();
  414. Rexx RXFile.charin(Rexx rFileName);
  415. Rexx RXFile.charin(long lStartPos, int iHowManyBytes);
  416. Rexx RXFile.charin(Rexx rFileName, long lStartPos, int iHowManyBytes);
  417.  
  418. This method gets one or more bytes from the standard input or
  419. a currently opened stream.
  420.  
  421. The methods which include also rFileName allow to close the currently opened
  422. stream and open the new one before actually doing the work without issueing
  423. a separate .stream command. These methods default to read AND write
  424. capabilities.
  425.  
  426. More in details:
  427.  
  428. Rexx RXFile.charin();
  429.  
  430. Returns the next byte from the currently used stream.
  431. If no stream is currently open, it returns the next byte
  432. from the standard input.
  433.  
  434. Rexx RXFile.charin(long lStartPos, int iHowManyBytes);
  435.  
  436. *This method works with files only, no standard input.*
  437.  
  438. Returns lHowManyBytes, starting from the absolute position lStartPos.
  439. If you specify a value of 0 (zero) for lStartPos, the bytes after
  440. the current cursor position in the stream will be read.
  441. (The first character in the stream is numbered 1)
  442.  
  443.  
  444. 2.3.7 ** The LINEIN method **
  445. -----------------------------
  446.  
  447. Rexx RXFile.linein();
  448. Rexx RXFile.linein(Rexx rFileName);
  449. Rexx RXFile.linein(int iLine, int iCount);
  450. Rexx RXFile.linein(Rexx rFileName, int iLine, int iCount);
  451.  
  452. This method returns zero or one lines of **ASCII** characters
  453. from the standard input or the stream in use.
  454.  
  455. The methods which include also rFileName allow to close the currently opened
  456. stream and open the new one before actually doing the work without issueing
  457. a separate .stream method. These methods default to read AND write
  458. capabilities.
  459.  
  460. More in details:
  461.  
  462. Rexx RXFile.linein();
  463.  
  464. Returns the next line from a stream, or from the stdin if no stream
  465. is currently open.
  466.  
  467. Rexx RXFile.linein(int iLine, int iCount);
  468.  
  469. *This method works with files only, no standard input.*
  470.  
  471. Returns iCount lines (where iCount can be only zero or one) from
  472. the currently in use stream, starting from position iLine
  473. where iLine can be zero (read the next line), or one (read the
  474. first line of the stream).
  475. Why to get zero lines? Because this way we have an alternative way
  476. to position the cursor at the beginning of the file.
  477.  
  478. Rexx RXFile.linein(Rexx rFileName);
  479.  
  480. *This method works with files only, no standard input.*
  481.  
  482. Returns the first line from stream rFileName (thus opening it with both read
  483. and write access permissions, as well as closing a precedently open file if any).
  484. After this operation, the currently opened file is rFileName.
  485.  
  486.  
  487. 2.3.8 ** The CHAROUT method **
  488. ------------------------------
  489.  
  490. Rexx RXFile.charout(Rexx rToWrite);
  491. Rexx RXFile.charout(Rexx rToWrite, long lStartPos);
  492. Rexx RXFile.charout(Rexx rFileName, Rexx rToWrite);
  493. Rexx RXFile.charout(Rexx rFileName, Rexx rToWrite, long lStartPos);
  494.  
  495. This method is used to write a string on a stream, or on stdout.
  496.  
  497. The latter two syntaxes allow to start working on a new file without issueing
  498. a separate stream method.
  499.  
  500. More in details:
  501.  
  502. Rexx RXFile.charout(Rexx rToWrite);
  503.  
  504. Writes the Rexx string rToWrite to the currently opened stream, at the
  505. current cursor position. If no stream is in use, the string is
  506. put on stdout (usually the screen).
  507.  
  508. Rexx RXFile.charout(Rexx rToWrite, long lStartPos);
  509.  
  510. *This method works with files only, no standard input.*
  511.  
  512. This version of the method also allows to specify an absolute
  513. starting position for the write on the stream. If lStartPos
  514. is equal to zero, then the write will occur at the current
  515. cursor position in the stream.
  516.  
  517.  
  518. 2.3.9 ** The LINEOUT method **
  519. ------------------------------
  520.  
  521. Rexx RXFile.lineout(Rexx rToWrite);
  522. Rexx RXFile.lineout(Rexx rToWrite, long lStartPos);
  523. Rexx RXFile.lineout(Rexx rFileName, Rexx rToWrite);
  524. Rexx RXFile.lineout(Rexx rFileName, Rexx rToWrite, long lStartPos);
  525.  
  526. This method is used to write a string adding a CR+LF (\r\n)
  527. or a LF (\n) (depending on how/if you called SETPARMS) on a stream, 
  528. or on stdout.
  529.  
  530. The latter two syntaxes allow to start working on a new file without issueing
  531. a separate stream method.
  532.  
  533. More in details:
  534.  
  535. Rexx RXFile.lineout(Rexx rToWrite);
  536.  
  537. Writes the Rexx string rToWrite to the currently opened stream, at the
  538. current cursor position, and adds a CR+LF or LF at the end of it.
  539. If no stream is in use, the string is put on stdout (usually the screen).
  540.  
  541. Rexx RXFile.lineout(Rexx rToWrite, long lStartPos);
  542.  
  543. *This method works with files only, no standard input.*
  544.  
  545. This version of the method also allows to specify an absolute
  546. starting position for the write on the stream. If lStartPos
  547. is equal to zero, then the write will occur at the current
  548. cursor position in the stream. 
  549. Please note that lStartPos can only be assigned the values zero or one,
  550. one meaning "write at the beginning of the file" and zero meaning
  551. "write at the current cursor position in the stream".
  552.  
  553.  
  554. The next methods are not ported from REXX. However, since they are
  555. very useful when dealing with I/O procedures, I have included them
  556. in the RXFile package.
  557.  
  558.  
  559. 2.3.10 ** The DELETE method **
  560. ------------------------------
  561.  
  562. Rexx RXFile.delete(Rexx FileName);
  563.  
  564. This method deletes a file.
  565.  
  566.  
  567. 2.3.11 ** The RENAME method **
  568. ------------------------------
  569.  
  570. Rexx RXFile.rename(Rexx OldFileName, Rexx NewFileName);
  571.  
  572. This method renames OldFileName into NewFileName.
  573.  
  574.  
  575. 2.3.12 ** The MKDIR method **
  576. -----------------------------
  577.  
  578. Rexx RXFile.mkdir(Rexx DirName);
  579.  
  580. Creates the directory DirName.
  581.  
  582.  
  583. 2.3.13 ** The MKDIRS method **
  584. ------------------------------
  585.  
  586. Rexx RXFile.mkdirs(Rexx DirName);
  587.  
  588. Creates the directory that comes last in DirName, 
  589. and all the preceding directories if they are not present.
  590.  
  591. i.e. if you have DirName set to "/usr/max/I/LOVE/WARP/CONNECT",
  592. and you don't have the directories I, LOVE, WARP and CONNECT, but
  593. you have usr and max, this function will create all of the ones that
  594. are not there, where mkdir would have failed since to create CONNECT
  595. you had to have all of usr, max, I, LOVE, WARP already created.
  596.  
  597. YMMV. This is the one API I have never tested. :)
  598.  
  599.  
  600. 2.3.14 ** The PROPERTIES method **
  601. ----------------------------------
  602.  
  603. Rexx RXFile.properties(Rexx FileName);
  604.  
  605. Returns the properties of the specified file or directory.
  606.  
  607. Properties:
  608.  
  609. The returned string is a four character string; every character
  610. can be '-' if the property is not valid for FileName or:
  611.  
  612.  f if the specified FileName refers to a file.
  613.  d if the specified FileName refers to a directory.
  614.  w if the specified FileName is writable.
  615.  r if the specified FileName is readable.
  616.  
  617. Example: 'f-wr' means that FileName is a file and we have both
  618. read and write permissions for it.
  619.  
  620.  
  621. 2.3.15 ** The FILETREE method **
  622. --------------------------------
  623.  
  624. Rexx[] RXFile.filetree(Rexx DirName);
  625.  
  626. This method returns all the file names for the specified directory.
  627. If the directory name is invalid (if there is not such a directory)
  628. you will get the "NOTREADY:NOSUCHDIRECTORY" error as the first and
  629. unique element of the returned array.
  630. If the directory is empty you will get "NOTREADY:DIRECTORYISEMPTY".
  631.  
  632.  
  633. 2.3.16 ** The SETPARMS method **
  634. --------------------------------
  635.  
  636. Rexx RXFile.setparms(boolean bSepCurs, boolean bRN);
  637.  
  638. This method, to be issued before opening any file (but only if
  639. needed), is used to define some RXFile options.
  640.  
  641. When bSepCurs is 1, you have two distinct cursors, one for read
  642. and one for write. Otherwise, you only have one cursor (this is
  643. the default, and it's also the way OS/2 REXX works).
  644.  
  645. When bRN is 1, the character used to do a newline is \r\n (dec 13 10);
  646. when this parameter is set to zero, the newline is only \n .
  647. This property is set upon RXFile variable's instantiation to follow
  648. whatever is the system's default
  649.  
  650.  
  651. 2.3.17 ** The GETPARMS method **
  652. --------------------------------
  653.  
  654. Rexx RXFile.getparms();
  655.  
  656. This method is used to retrieve the status of some RXFile options.
  657.  
  658. It returns a Rexx string which is composed of two binary digits, ie "11".
  659.  
  660. When the first is 1, you have two distinct cursors, one for read
  661. and one for write. Otherwise, you only have one cursor (this is
  662. the default, and it's also the way OS/2 REXX works).
  663.  
  664. When the second is 1, the character used to do a newline is 
  665. \r\n (dec 13 10); when this parameter is set to zero, 
  666. the newline is only \n . This property is set upon instantiation to follow
  667. whatever is the system's default, but can be changed with the SETPARMS method.
  668.  
  669.  
  670. 2.3.18  ** The ADDCURSOR method **
  671. ----------------------------------
  672.  
  673. Rexx RXFile.addcursor(Rexx rKey, long lCursPos);
  674.  
  675. This method stores (into the variable's memory, which is unique for every
  676. RXFile instance) the lCursPos cursor position, under the name rKey. 
  677. You can retrieve this information later, with getcursor, or delete it with 
  678. delcursor or delallcursors.
  679.  
  680. This is useful when you have to work on many points of a file.
  681.  
  682.  
  683. 2.3.19  ** The GETCURSOR method **
  684. ----------------------------------
  685.  
  686. Rexx RXFile.getcursor(Rexx rKey);
  687.  
  688. This method retrieve (from the variable's memory, which is unique for every
  689. RXFile instance) the cursor position which has been stored under the name rKey. 
  690. If you request a cursor position that hasn't been stored, you'll get the message
  691. "Error: no such cursor." instead of a Rexx string representing a long.
  692.  
  693.  
  694. 2.3.20  ** The DELCURSOR method **
  695. ----------------------------------
  696.  
  697. Rexx RXFile.delcursor(Rexx rKey);
  698.  
  699. This method deletes (from the variable's memory, which is unique for every
  700. RXFile instance) the cursor position which has been stored under the name rKey. 
  701.  
  702.  
  703. 2.3.21  ** The DELALLCURSORS method **
  704. --------------------------------------
  705.  
  706. Rexx RXFile.delallcursors();
  707.  
  708. This method deletes (from the variable's memory, which is unique for every
  709. RXFile instance) all of the cursor positions which have been stored. 
  710.  
  711.  
  712. 2.3.22  ** The ATTACHTOINPUTSTREAM method **
  713. --------------------------------------------
  714.  
  715. Rexx RXFile.attachtoinputstream(InputStream is)
  716.  
  717. This method redirects the InputStream 'is' to the default InputStream for that
  718. RXFile instance (i.e. replacing user input from console). You didn't know
  719. that RXFile had an InputStream, or you didn't find notice of this fact anywhere?
  720. That's because it's a private property. Now you can interact with it this way.
  721.  
  722.  
  723. 2.3.23  ** The ATTACHTOOUTPUTSTREAM method **
  724. ---------------------------------------------
  725.  
  726. Rexx RXFile.attachtooutputstream(OutputStream os)
  727.  
  728. This method redirects the OutputStream 'os' to the default OutputStream for that
  729. RXFile instance (i.e. replacing console output).
  730.  
  731.  
  732. 2.3.24 ** The COPY method **
  733. ------------------------------
  734.  
  735. Rexx RXFile.copy(Rexx SourceFileName, Rexx TargetFileName);
  736.  
  737. This method copies SourceFileName into TargetFileName (overwriting it if necessary).
  738.  
  739.  
  740.  
  741.  
  742.  
  743. 3. O T H E R   S T U F F
  744. ------------------------
  745.  
  746.  
  747.  
  748. 3.1 THIS PACKAGE CONTENTS
  749. -------------------------
  750.  
  751. This package should contain:
  752.  
  753.  RXFile.doc   .. this document.
  754.  guru.doc     .. working code to use in your programs.
  755.  RXFile.class .. the RXFile class for NetRexx (and Java).
  756.  *.nrx ..  => Examples for the RXFile class.
  757.  *.cmd ..   => Examples for the RXFile class (REXX files).
  758.  
  759.  
  760.  
  761. 3.2 LICENSE
  762. ------------
  763.  
  764. RXFile is not public domain: it is freeware. It means that you can freely
  765. use it in your programs, be them for personal use and/or commercial use.
  766. However, the sources are not provided, and you cannot modify or disassemble
  767. the class, in any way. Also, if you re-distribute this program, you cannot
  768. charge any money for it, apart from media costs (eg. diskette cost).
  769. If you plan to use this class on a project of yours, you must give credits
  770. to the author (Max Marsiglietti) of this.
  771.  
  772. I am not responsible or liable in any way for damages 
  773. deriving from the use of this product. Use it at your own risk.
  774.  
  775.  
  776. 3.3 CONTACTING THE AUTHOR
  777. -------------------------
  778.  
  779. This library is intended to follow more closely possible the REXX language I/O
  780. functions. If you find any discrepancy from them, or bugs, please report all
  781. of your comments to:
  782.  
  783.  Max Marsiglietti, 
  784.  
  785.  E-mail:
  786.   maxmars@pianeta.it (Internet), 2:332/529.12 (Fidonet)
  787.  
  788.  Snail Mail:
  789.   V.Landino 13, 
  790.   41049, Sassuolo (MO)
  791.   Italy.
  792.  
  793.  
  794.  
  795. 3.4 History
  796. -----------
  797.  
  798. 1.13 .. (08-may-97) Fixed the behaviour of linein:
  799.          an EOF now correctly reports EOF instead of
  800.          throwing a NullPointerException exception.
  801. 1.12 .. (19-apr-97) Fixed a bug, added the COPY method.
  802. 1.11 .. (13-feb-97) Fixed a bug in mkdirs.
  803. 1.10 .. (19-dec-96) Added support for Mac line termination (\r).
  804. 1.09 .. (03-dec-96) Fixed a bug in filetree, added new return 
  805.         codes for that function.
  806. 1.08 .. (12-nov-96) Fixed a problem with lineout console output,
  807.         added redirected in/out capabilities (attachtoinputstream
  808.         and attachtooutputstream). Reworked a bit some internals.
  809. 1.07 .. Internal changes, for synchronization with RXDbase.
  810. 1.06 .. Fixed the 'rename' function.
  811. 1.05 .. Now linein should work with both \r\n and \n terminated ASCII
  812.         files, independently from the platform.
  813. 1.04 .. Fixed strange behaviour of linein. Compiled with NetRexx 0.81.
  814. 1.03 .. Bug fixes to the docs and internal changes for RXDbase.
  815. 1.02 .. Bug fixes to stream and lineout. Works with NetRexx 0.79.
  816. 1.01 .. Added a cursor stack: addcursor, getcursor, delcursor,
  817.                               delallcursors functions added.
  818. 1.00 .. First implementation of RXFile.
  819.  
  820. Thanks, and good work with RXFile!
  821.